home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 November: Tool Chest / Dev.CD Nov 00 TC Disk 1.toast / Sample Code / Graphics 2D / Restore Screen Cluts / EmergMem.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-09-28  |  8.9 KB  |  200 lines  |  [TEXT/CWIE]
  1. /*
  2.     File:        EmergMem.h
  3.  
  4.     Contains:    EmergMem contains routines to handle emergency memory situations.  This is
  5.                 used for Toolbox routines that either don’t check for memory-full errors, or
  6.                 that call _SysErr when they can’t allocate the memory that they need.  The
  7.                 purpose of the routines in this file is to make sure that these toolbox
  8.                 routines always have the memory they need.
  9.  
  10.     Written by:  Forrest Tanaka    
  11.  
  12.     Copyright:    Copyright © 1988-1999 by Apple Computer, Inc., All Rights Reserved.
  13.  
  14.                 You may incorporate this Apple sample source code into your program(s) without
  15.                 restriction. This Apple sample source code has been provided "AS IS" and the
  16.                 responsibility for its operation is yours. You are not permitted to redistribute
  17.                 this Apple sample source code as "Apple sample source code" after having made
  18.                 changes. If you're going to re-distribute the source, we require that you make
  19.                 it clear in the source that the code was descended from Apple sample source
  20.                 code, but that you've made changes.
  21.  
  22.     Change History (most recent first):
  23.                 7/13/1999    Karl Groethe    Updated for Metrowerks Codewarror Pro 2.1
  24.                 
  25.  
  26. */
  27. #ifndef __EMERGMEM__
  28. #define __EMERGMEM__
  29.  
  30. /******************************************************************************\
  31. * Header Files
  32. \******************************************************************************/
  33.  
  34. #include <Types.h>
  35. #include <Memory.h>
  36.  
  37.  
  38. /******************************************************************************\
  39. * Constants
  40. \******************************************************************************/
  41.  
  42. #define kAllocApp true /* For NewPtrMargin/NewHandleMargin for app heap alloc */
  43. #define kAllocClr true /* For NewPtrMargin/NewHandleMargin to clear mem block */
  44.  
  45.  
  46. /******************************************************************************\
  47. * InstallAppGZ - Installs the application grow zone proc
  48. *
  49. * This routine is called whenever this application’s simple grow-zone procedure
  50. * (see EmergMem.c for the source for the grow-zone procedure) is to be
  51. * installed.  From this point on, any requests for memory by this application or
  52. * the system invoke our grow-zone procedure if there isn’t enough memory to
  53. * satisfy the request.
  54. \******************************************************************************/
  55.  
  56. void InstallAppGZ(void);
  57.  
  58.  
  59. /******************************************************************************\
  60. * DeinstallAppGZ - install the application grow zone proc
  61. *
  62. * This routine is called whenever this application’s simple grow-zone procedure
  63. * (see EmergMem.c for the source for the grow-zone procedure) is to be
  64. * deinstalled.  From this point on, any requests for memory by this application
  65. * or the system return memFullErr if there isn’t enough memory to satisfy the
  66. * request.
  67. \******************************************************************************/
  68.  
  69. void DeinstallAppGZ(void);
  70.  
  71.  
  72. /******************************************************************************\
  73. * InitEmergMem - Allocate emergency memory
  74. *
  75. * This is called at startup time to allocate the emergency memory block that can
  76. * be deallocated by the grow zone procedure (this application’s grow-zone
  77. * procedure is defined privately in EmergMem.c).  InitEmergMem also installs
  78. * this application’s grow-zone proc.
  79. *
  80. * If there isn’t enough memory to allocate the block of emergency memory, then
  81. * a subsequent call to FailLowMemory(0) returns TRUE.
  82. \******************************************************************************/
  83.  
  84. void InitEmergMem(void);
  85.  
  86.  
  87. /******************************************************************************\
  88. * RecoverEmergMem - Recover emergency memory
  89. *
  90. * This is called from the event loop if NoEmergMem indicates that the emergency
  91. * memory was deallocated by this application’s grow-zone procedure.  This
  92. * routine will attempt recover the emergency memory.  If this fails, then some
  93. * application options and commands are disabled until there is enough free
  94. * memory to enable them again.
  95. \******************************************************************************/
  96.  
  97. void RecoverEmergMem(void);
  98.  
  99.  
  100. /******************************************************************************\
  101. * FailLowMemory - Is there enough free space in heap to allocate memory?
  102. *
  103. * FailLowMemory is called any time a potentially significant amount of non-
  104. * temporary memory is about to be allocated.  It returns true if there’s enough
  105. * free space in the heap to allocate the requested amount of memory and still
  106. * have a significant amount of free space left over, and if the emergency memory
  107. * isn’t being used.  See EmergMem.c for the definition of “significant amount.”
  108. * "memRequest" specifies the number of bytes that are about to be allocated.
  109. *
  110. * This routine is also used even if the exact amount of memory about to be
  111. * allocated isn’t known.  In this case, zero is passed in memRequest.  If
  112. * FailLowMemory returns true, then there’s enough memory for the the emergency
  113. * memory and a significant amount of free memory.  If FailLowMemory returns
  114. * false, then either there isn’t a significant amount of free memory, or if the
  115. * emergency memory was deallocated by this application’s grow-zone procedure, or
  116. * both.  This is actually the usual way that I use this function, because I
  117. * normally use it for calls to the Toolbox, and there’s usually no reliable way
  118. * to determine how much memory the Toolbox is going to allocate.
  119. \******************************************************************************/
  120.  
  121. Boolean FailLowMemory(
  122.     long memRequest);
  123.  
  124.  
  125. /******************************************************************************\
  126. * NoEmergMem - Check to see if emergency memory is being used or not
  127. *
  128. * Before my application attempts to use more memory, I call this routine to
  129. * check if I'm already using my emergency memory.  If so, then I’d better
  130. * prepare to die or get my emergency memory back.
  131. \******************************************************************************/
  132.  
  133. Boolean NoEmergMem(void);
  134.  
  135.  
  136. /******************************************************************************\
  137. * NewHandleMargin - Create a new handle without using emergency memory
  138. *
  139. * Many toolbox routines simply call SysErr when they run out of memory.  That’s
  140. * not too cool, so I try to make certain that the memory they need is always
  141. * available by making sure that I never request so much memory that the toolbox
  142. * routines are in danger of running out of memory and calling SysErr.  This is
  143. * achieved by calling NewHandleMargin instead of NewHandle any time a
  144. * relocatable memory block is desired.  NewHandle returns memFullErr in MemErr
  145. * if there isn’t enough free contiguous space to satisfy the request.
  146. * NewHandleMargin returns nil if there isn’t enough memory to allocate a block
  147. * of the size specified by "requestedSize".
  148. *
  149. *     WARNING: Don’t depend on MemError after calling NewHandleMargin.  The
  150. *     only way to tell whether it succeeded or not is to compare the result
  151. *     against NIL.
  152. *
  153. * If "appHeapAlloc" is kAppHeap, then the block of memory is allocated in the
  154. * application’s heap.  If "appHeapAlloc" is !kAppHeap, then the block of
  155. * memory is allocated in the system heap.
  156. *
  157. * If "clearMem" is kAllocClr, then all the bytes in the block of memory are
  158. * cleared to zero.  If !kAllocClr is passed, then none of the bytes in the
  159. * block of memory are touched after being allocated.
  160. \******************************************************************************/
  161.  
  162. Handle NewHandleMargin(
  163.     Size    requestedSize,
  164.     Boolean appHeapAlloc,
  165.     Boolean clearMem);
  166.  
  167.  
  168. /******************************************************************************\
  169. * NewPtrMargin - Create a new pointer without using emergency memory
  170. *
  171. * Many toolbox routines simply call SysErr when they run out of memory.  That’s
  172. * not too cool, so I try to make certain that the memory they need is always
  173. * available by making sure that I never request so much memory that the toolbox
  174. * routines are in danger of running out of memory and calling SysErr.  This is
  175. * achieved by calling NewPtrMargin instead of NewPtr any time a non-relocatable
  176. * memory block is desired.  NewPtr returns memFullErr in MemErr if there isn’t
  177. * enough free contiguous space to satisfy the request.  NewPtrMargin returns nil
  178. * if there isn’t enough memory to allocated a block of the size specified by
  179. * "requestedSize".
  180. *
  181. *     WARNING: Don’t depend on MemError after calling NewPtrMargin.  The
  182. *     only way to tell whether it succeeded or not is to compare the result
  183. *     against NIL.
  184. *
  185. * If "appHeapAlloc" is kAppHeap, then the block of memory is allocated in the
  186. * application’s heap.  If "appHeapAlloc" is !kAppHeap, then the block of
  187. * memory is allocated in the system heap.
  188. *
  189. * If "clearMem" is kAllocClr, then all the bytes in the block of memory are
  190. * cleared to zero.  If !kAllocClr is passed, then none of the bytes in the
  191. * block of memory are touched after being allocated.
  192. \******************************************************************************/
  193.  
  194. Ptr NewPtrMargin(
  195.     Size    requestedSize,
  196.     Boolean appHeapAlloc,
  197.     Boolean clearMem);
  198.  
  199.  
  200. #endif